home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / strevc.z / strevc
Encoding:
Text File  |  2002-10-03  |  9.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      STREVC - compute some or all of the right and/or left eigenvectors of a
  10.      real upper quasi-triangular matrix T
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      SUBROUTINE STREVC( SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR,
  14.                         MM, M, WORK, INFO )
  15.  
  16.          CHARACTER      HOWMNY, SIDE
  17.  
  18.          INTEGER        INFO, LDT, LDVL, LDVR, M, MM, N
  19.  
  20.          LOGICAL        SELECT( * )
  21.  
  22.          REAL           T( LDT, * ), VL( LDVL, * ), VR( LDVR, * ), WORK( * )
  23.  
  24. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  25.      These routines are part of the SCSL Scientific Library and can be loaded
  26.      using either the -lscs or the -lscs_mp option.  The -lscs_mp option
  27.      directs the linker to use the multi-processor version of the library.
  28.  
  29.      When linking to SCSL with -lscs or -lscs_mp, the default integer size is
  30.      4 bytes (32 bits). Another version of SCSL is available in which integers
  31.      are 8 bytes (64 bits).  This version allows the user access to larger
  32.      memory sizes and helps when porting legacy Cray codes.  It can be loaded
  33.      by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
  34.      only one of the two versions; 4-byte integer and 8-byte integer library
  35.      calls cannot be mixed.
  36.  
  37. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  38.      STREVC computes some or all of the right and/or left eigenvectors of a
  39.      real upper quasi-triangular matrix T. The right eigenvector x and the
  40.      left eigenvector y of T corresponding to an eigenvalue w are defined by:
  41.  
  42.                   T*x = w*x,     y'*T = w*y'
  43.  
  44.      where y' denotes the conjugate transpose of the vector y.
  45.  
  46.      If all eigenvectors are requested, the routine may either return the
  47.      matrices X and/or Y of right or left eigenvectors of T, or the products
  48.      Q*X and/or Q*Y, where Q is an input orthogonal
  49.      matrix. If T was obtained from the real-Schur factorization of an
  50.      original matrix A = Q*T*Q', then Q*X and Q*Y are the matrices of right or
  51.      left eigenvectors of A.
  52.  
  53.      T must be in Schur canonical form (as returned by SHSEQR), that is, block
  54.      upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2
  55.      diagonal block has its diagonal elements equal and its off-diagonal
  56.      elements of opposite sign.  Corresponding to each 2-by-2 diagonal block
  57.      is a complex conjugate pair of eigenvalues and eigenvectors; only one
  58.      eigenvector of the pair is computed, namely the one corresponding to the
  59.      eigenvalue with positive imaginary part.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  71.  
  72.  
  73.  
  74. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  75.      SIDE    (input) CHARACTER*1
  76.              = 'R':  compute right eigenvectors only;
  77.              = 'L':  compute left eigenvectors only;
  78.              = 'B':  compute both right and left eigenvectors.
  79.  
  80.      HOWMNY  (input) CHARACTER*1
  81.              = 'A':  compute all right and/or left eigenvectors;
  82.              = 'B':  compute all right and/or left eigenvectors, and
  83.              backtransform them using the input matrices supplied in VR and/or
  84.              VL; = 'S':  compute selected right and/or left eigenvectors,
  85.              specified by the logical array SELECT.
  86.  
  87.      SELECT  (input/output) LOGICAL array, dimension (N)
  88.              If HOWMNY = 'S', SELECT specifies the eigenvectors to be
  89.              computed.  If HOWMNY = 'A' or 'B', SELECT is not referenced.  To
  90.              select the real eigenvector corresponding to a real eigenvalue
  91.              w(j), SELECT(j) must be set to .TRUE..  To select the complex
  92.              eigenvector corresponding to a complex conjugate pair w(j) and
  93.              w(j+1), either SELECT(j) or SELECT(j+1) must be set to .TRUE.;
  94.              then on exit SELECT(j) is .TRUE. and SELECT(j+1) is .FALSE..
  95.  
  96.      N       (input) INTEGER
  97.              The order of the matrix T. N >= 0.
  98.  
  99.      T       (input) REAL array, dimension (LDT,N)
  100.              The upper quasi-triangular matrix T in Schur canonical form.
  101.  
  102.      LDT     (input) INTEGER
  103.              The leading dimension of the array T. LDT >= max(1,N).
  104.  
  105.      VL      (input/output) REAL array, dimension (LDVL,MM)
  106.              On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must contain
  107.              an N-by-N matrix Q (usually the orthogonal matrix Q of Schur
  108.              vectors returned by SHSEQR).  On exit, if SIDE = 'L' or 'B', VL
  109.              contains:  if HOWMNY = 'A', the matrix Y of left eigenvectors of
  110.              T; VL has the same quasi-lower triangular form as T'. If T(i,i)
  111.              is a real eigenvalue, then the i-th column VL(i) of VL  is its
  112.              corresponding eigenvector. If T(i:i+1,i:i+1) is a 2-by-2 block
  113.              whose eigenvalues are complex-conjugate eigenvalues of T, then
  114.              VL(i)+sqrt(-1)*VL(i+1) is the complex eigenvector corresponding
  115.              to the eigenvalue with positive real part.  if HOWMNY = 'B', the
  116.              matrix Q*Y; if HOWMNY = 'S', the left eigenvectors of T specified
  117.              by SELECT, stored consecutively in the columns of VL, in the same
  118.              order as their eigenvalues.  A complex eigenvector corresponding
  119.              to a complex eigenvalue is stored in two consecutive columns, the
  120.              first holding the real part, and the second the imaginary part.
  121.              If SIDE = 'R', VL is not referenced.
  122.  
  123.      LDVL    (input) INTEGER
  124.              The leading dimension of the array VL.  LDVL >= max(1,N) if SIDE
  125.              = 'L' or 'B'; LDVL >= 1 otherwise.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      VR      (input/output) REAL array, dimension (LDVR,MM)
  141.              On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must contain
  142.              an N-by-N matrix Q (usually the orthogonal matrix Q of Schur
  143.              vectors returned by SHSEQR).  On exit, if SIDE = 'R' or 'B', VR
  144.              contains:  if HOWMNY = 'A', the matrix X of right eigenvectors of
  145.              T; VR has the same quasi-upper triangular form as T. If T(i,i) is
  146.              a real eigenvalue, then the i-th column VR(i) of VR  is its
  147.              corresponding eigenvector. If T(i:i+1,i:i+1) is a 2-by-2 block
  148.              whose eigenvalues are complex-conjugate eigenvalues of T, then
  149.              VR(i)+sqrt(-1)*VR(i+1) is the complex eigenvector corresponding
  150.              to the eigenvalue with positive real part.  if HOWMNY = 'B', the
  151.              matrix Q*X; if HOWMNY = 'S', the right eigenvectors of T
  152.              specified by SELECT, stored consecutively in the columns of VR,
  153.              in the same order as their eigenvalues.  A complex eigenvector
  154.              corresponding to a complex eigenvalue is stored in two
  155.              consecutive columns, the first holding the real part and the
  156.              second the imaginary part.  If SIDE = 'L', VR is not referenced.
  157.  
  158.      LDVR    (input) INTEGER
  159.              The leading dimension of the array VR.  LDVR >= max(1,N) if SIDE
  160.              = 'R' or 'B'; LDVR >= 1 otherwise.
  161.  
  162.      MM      (input) INTEGER
  163.              The number of columns in the arrays VL and/or VR. MM >= M.
  164.  
  165.      M       (output) INTEGER
  166.              The number of columns in the arrays VL and/or VR actually used to
  167.              store the eigenvectors.  If HOWMNY = 'A' or 'B', M is set to N.
  168.              Each selected real eigenvector occupies one column and each
  169.              selected complex eigenvector occupies two columns.
  170.  
  171.      WORK    (workspace) REAL array, dimension (3*N)
  172.  
  173.      INFO    (output) INTEGER
  174.              = 0:  successful exit
  175.              < 0:  if INFO = -i, the i-th argument had an illegal value
  176.  
  177. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  178.      The algorithm used in this program is basically backward (forward)
  179.      substitution, with scaling to make the the code robust against possible
  180.      overflow.
  181.  
  182.      Each eigenvector is normalized so that the element of largest magnitude
  183.      has magnitude 1; here the magnitude of a complex number (x,y) is taken to
  184.      be |x| + |y|.
  185.  
  186.  
  187. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  188.      INTRO_LAPACK(3S), INTRO_SCSL(3S)
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))                                                          SSSSTTTTRRRREEEEVVVVCCCC((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      This man page is available only online.
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.